Developer CD Series 1997 October: Mac OS SDK

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / QD3DRenderer.h < prev next >

Wrap

C/C++ Source or Header | 1997-08-13 | 43.9 KB | 1,348 lines | [TEXT/MPS ]

/****************************************************************************** ** ** ** Module: QD3DRenderer.h ** ** ** ** ** ** Purpose: Renderer types and routines ** ** ** ** ** ** ** ** Copyright (C) 1992-1997 Apple Computer, Inc. All rights reserved. ** ** ** ** ** *****************************************************************************/ #ifndef QD3DRenderer_h #define QD3DRenderer_h #include "QD3D.h" #include "QD3DView.h" #include "QD3DSet.h" #if defined(PRAGMA_ONCE) && PRAGMA_ONCE #pragma once #endif /* PRAGMA_ONCE */ #if defined(OS_MACINTOSH) && OS_MACINTOSH #if defined(__xlc__) || defined(__XLC121__) #pragma options enum=small #endif #include <Events.h> #if defined(__xlc__) || defined(__XLC121__) #pragma options enum=reset #pragma options enum=int #pragma options align=power #elif defined(__MWERKS__) #pragma enumsalwaysint on #pragma options align=native #elif defined(__MRC__) || defined(__SC__) #if __option(pack_enums) #define PRAGMA_ENUM_RESET_QD3DRENDER 1 #endif #pragma options(!pack_enums) #pragma options align=power #endif #endif /* OS_MACINTOSH */ #if defined(WINDOW_SYSTEM_WIN32) && WINDOW_SYSTEM_WIN32 #include "windows.h" #endif /* WINDOW_SYSTEM_WIN32 */ #ifdef __cplusplus extern "C" { #endif /* __cplusplus */ /****************************************************************************** ** ** ** User Interface Things ** ** ** *****************************************************************************/ #if defined(WINDOW_SYSTEM_MACINTOSH) && WINDOW_SYSTEM_MACINTOSH /* * A callback to an application's event handling code. This is needed to * support movable modal dialogs. The dialog's event filter calls this * callback with events it does not handle. * If an application handles the event it should return kQ3True. * If the application does not handle the event it must return kQ3False and * the dialog's event filter will pass the event to the system unhandled. */ typedef TQ3Boolean (QD3D_CALLBACK *TQ3MacOSDialogEventHandler)( const EventRecord *event); typedef struct TQ3DialogAnchor { TQ3MacOSDialogEventHandler clientEventHandler; } TQ3DialogAnchor; #elif defined(WINDOW_SYSTEM_WIN32) && WINDOW_SYSTEM_WIN32 typedef struct TQ3DialogAnchor { HWND ownerWindow; } TQ3DialogAnchor; #else /* ! WINDOW_SYSTEM_MACINTOSH && ! WINDOW_SYSTEM_WIN32 */ typedef struct TQ3DialogAnchor { void *notUsed; /* place holder */ } TQ3DialogAnchor; #endif /* ! WINDOW_SYSTEM_MACINTOSH && ! WINDOW_SYSTEM_WIN32 */ /****************************************************************************** ** ** ** Renderer Functions ** ** ** *****************************************************************************/ QD3D_EXPORT TQ3RendererObject QD3D_CALL Q3Renderer_NewFromType( TQ3ObjectType rendererObjectType); QD3D_EXPORT TQ3ObjectType QD3D_CALL Q3Renderer_GetType( TQ3RendererObject renderer); /* * Q3Renderer_IsInteractive * Determine if this renderer is intended to be used interactively. */ QD3D_EXPORT TQ3Boolean QD3D_CALL Q3Renderer_IsInteractive( TQ3RendererObject renderer); /* * Q3Renderer_HasModalConfigure * Determine if this renderer has a modal settings dialog. * * Q3Renderer_ModalConfigure * Have the renderer pop up a modal dialog box to configure its settings. * dialogAnchor - is platform specific data passed by the client to support * movable modal dialogs. * MacOS: this is a callback to the calling application's event handler. * The renderer calls this function with events not handled by the * settings dialog. This is necessary in order to support movable modal * dialogs. An application's event handler must return kQ3True if it * handles the event passed to the callback or kQ3False if not. * An application which doesn't want to support a movable modal configure * dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor. * Win32: this is the HWND of the owning window (typically an application's * main window). * canceled - returns a boolean inditacating that the user canceled the * dialog. * */ QD3D_EXPORT TQ3Boolean QD3D_CALL Q3Renderer_HasModalConfigure( TQ3RendererObject renderer); QD3D_EXPORT TQ3Status QD3D_CALL Q3Renderer_ModalConfigure( TQ3RendererObject renderer, TQ3DialogAnchor dialogAnchor, TQ3Boolean *canceled); /* * Q3RendererClass_GetNickNameString * Allows an application to get a renderers name string, the * renderer is responsible for storing this in a localizable format * for example as a resource. This string can then be used to provide * a selection mechanism for an application (for example in a menu). * * If this call returns nil in the supplied string, then the App may * choose to use the class name for the renderer. You should always * try to get the name string before using the class name, since the * class name is not localizable. */ QD3D_EXPORT TQ3Status QD3D_CALL Q3RendererClass_GetNickNameString( TQ3ObjectType rendererClassType, TQ3ObjectClassNameString rendererClassString); /* * Q3Renderer_GetConfigurationData * Allows an application to collect private renderer configuration data * which it will then save. For example in a preference file or in a * style template. An application should tag this data with the * Renderer's object name. * * if dataBuffer is NULL actualDataSize returns the required size in * bytes of a data buffer large enough to store private data. * * bufferSize is the actual size of the memory block pointed to by * dataBuffer * * actualDataSize - on return the actual number of bytes written to the * buffer or if dataBuffer is NULL the required size of dataBuffer * */ QD3D_EXPORT TQ3Status QD3D_CALL Q3Renderer_GetConfigurationData( TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize); QD3D_EXPORT TQ3Status QD3D_CALL Q3Renderer_SetConfigurationData( TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize); /****************************************************************************** ** ** ** Interactive Renderer Specific Functions ** ** ** *****************************************************************************/ /* * CSG IDs attribute */ #define kQ3AttributeTypeConstructiveSolidGeometryID \ Q3_OBJECT_TYPE('c','s','g','i') /* * Object IDs, to be applied as attributes on geometries */ #define kQ3SolidGeometryObjNone -1 #define kQ3SolidGeometryObjA 0 #define kQ3SolidGeometryObjB 1 #define kQ3SolidGeometryObjC 2 #define kQ3SolidGeometryObjD 3 #define kQ3SolidGeometryObjE 4 /* * Possible CSG equations */ typedef enum TQ3CSGEquation { kQ3CSGEquationAandB = (int)0x88888888, kQ3CSGEquationAandnotB = 0x22222222, kQ3CSGEquationAanBonCad = 0x2F222F22, kQ3CSGEquationnotAandB = 0x44444444, kQ3CSGEquationnAaBorCanB = 0x74747474 } TQ3CSGEquation; typedef enum TQ3HiddenSurfaceRemovalMode { kQ3HiddenSurfaceRemovalMode_None, kQ3HiddenSurfaceRemovalMode_Shallow, kQ3HiddenSurfaceRemovalMode_Deep } TQ3HiddenSurfaceRemovalMode; QD3D_EXPORT TQ3Status QD3D_CALL Q3InteractiveRenderer_SetCSGEquation( TQ3RendererObject renderer, TQ3CSGEquation equation); QD3D_EXPORT TQ3Status QD3D_CALL Q3InteractiveRenderer_GetCSGEquation( TQ3RendererObject renderer, TQ3CSGEquation *equation); QD3D_EXPORT TQ3Status QD3D_CALL Q3InteractiveRenderer_SetPreferences( TQ3RendererObject renderer, long vendorID, long engineID); QD3D_EXPORT TQ3Status QD3D_CALL Q3InteractiveRenderer_GetPreferences( TQ3RendererObject renderer, long *vendorID, long *engineID); QD3D_EXPORT TQ3Status QD3D_CALL Q3InteractiveRenderer_SetDoubleBufferBypass( TQ3RendererObject renderer, TQ3Boolean bypass); QD3D_EXPORT TQ3Status QD3D_CALL Q3InteractiveRenderer_GetDoubleBufferBypass( TQ3RendererObject renderer, TQ3Boolean *bypass); QD3D_EXPORT TQ3Status QD3D_CALL Q3InteractiveRenderer_SetRAVEContextHints( TQ3RendererObject renderer, unsigned long RAVEContextHints); QD3D_EXPORT TQ3Status QD3D_CALL Q3InteractiveRenderer_GetRAVEContextHints( TQ3RendererObject renderer, unsigned long *RAVEContextHints); QD3D_EXPORT TQ3Status QD3D_CALL Q3InteractiveRenderer_SetRAVETextureFilter( TQ3RendererObject renderer, unsigned long RAVEtextureFilterValue); QD3D_EXPORT TQ3Status QD3D_CALL Q3InteractiveRenderer_GetRAVETextureFilter( TQ3RendererObject renderer, unsigned long *RAVEtextureFilterValue); /****************************************************************************** ** ** ** Renderer View Tools ** ** ** ** You may only call these methods from a plug-in ** ** ** *****************************************************************************/ /* * Call by a renderer to call the user "idle" method, with progress * information. * * Pass in (view, 0, n) on first call * Pass in (view, 1..n-1, n) during rendering * Pass in (view, n, n) upon completion * * Note: The user must have supplied an idleProgress method with * Q3XView_SetIdleProgressMethod. Otherwise, the generic idle method is * called with no progress data. e.g. the Q3View_SetIdleMethod method * is called instead. (current and final are ignored, essentially.) * * Returns kQ3Failure if rendering is cancelled. */ QD3D_EXPORT TQ3Status QD3D_CALL Q3XView_IdleProgress( TQ3ViewObject view, unsigned long current, unsigned long completed); /* * Called by an asynchronous renderer when it completes a frame. */ QD3D_EXPORT TQ3Status QD3D_CALL Q3XView_EndFrame( TQ3ViewObject view); /****************************************************************************** ** ** ** Renderer AttributeSet Tools ** ** ** ** You may only call these methods from a plug-in ** ** ** *****************************************************************************/ /* * Faster access to geometry attribute sets. * * Returns pointer to INTERNAL data structure for elements and attributes * in an attributeSet, or NULL if no attribute exists. * * For attributes of type kQ3AttributeType..., the internal data structure * is identical to the data structure used in Q3AttributeSet_Add. */ QD3D_EXPORT void *QD3D_CALL Q3XAttributeSet_GetPointer( TQ3AttributeSet attributeSet, TQ3AttributeType attributeType); #define kQ3XAttributeMaskNone \ 0L #define kQ3XAttributeMaskSurfaceUV \ (1 << (kQ3AttributeTypeSurfaceUV - 1)) #define kQ3XAttributeMaskShadingUV \ (1 << (kQ3AttributeTypeShadingUV - 1)) #define kQ3XAttributeMaskNormal \ (1 << (kQ3AttributeTypeNormal - 1)) #define kQ3XAttributeMaskAmbientCoefficient \ (1 << (kQ3AttributeTypeAmbientCoefficient - 1)) #define kQ3XAttributeMaskDiffuseColor \ (1 << (kQ3AttributeTypeDiffuseColor - 1)) #define kQ3XAttributeMaskSpecularColor \ (1 << (kQ3AttributeTypeSpecularColor - 1)) #define kQ3XAttributeMaskSpecularControl \ (1 << (kQ3AttributeTypeSpecularControl - 1)) #define kQ3XAttributeMaskTransparencyColor \ (1 << (kQ3AttributeTypeTransparencyColor - 1)) #define kQ3XAttributeMaskSurfaceTangent \ (1 << (kQ3AttributeTypeSurfaceTangent - 1)) #define kQ3XAttributeMaskHighlightState \ (1 << (kQ3AttributeTypeHighlightState - 1)) #define kQ3XAttributeMaskSurfaceShader \ (1 << (kQ3AttributeTypeSurfaceShader - 1)) #define kQ3XAttributeMaskCustomAttribute 0x80000000 #define kQ3XAttributeMaskAll \ ( \ kQ3XAttributeMaskSurfaceUV | \ kQ3XAttributeMaskShadingUV | \ kQ3XAttributeMaskNormal | \ kQ3XAttributeMaskAmbientCoefficient | \ kQ3XAttributeMaskDiffuseColor | \ kQ3XAttributeMaskSpecularColor | \ kQ3XAttributeMaskSpecularControl | \ kQ3XAttributeMaskTransparencyColor | \ kQ3XAttributeMaskSurfaceTangent | \ kQ3XAttributeMaskHighlightState | \ kQ3XAttributeMaskSurfaceShader | \ kQ3XAttributeMaskCustomAttribute \ ) #define kQ3XAttributeMaskInherited \ ( \ kQ3XAttributeMaskSurfaceUV | \ kQ3XAttributeMaskShadingUV | \ kQ3XAttributeMaskNormal | \ kQ3XAttributeMaskAmbientCoefficient | \ kQ3XAttributeMaskDiffuseColor | \ kQ3XAttributeMaskSpecularColor | \ kQ3XAttributeMaskSpecularControl | \ kQ3XAttributeMaskTransparencyColor | \ kQ3XAttributeMaskSurfaceTangent | \ kQ3XAttributeMaskHighlightState \ ) #define kQ3XAttributeMaskInterpolated \ ( \ kQ3XAttributeMaskSurfaceUV | \ kQ3XAttributeMaskShadingUV | \ kQ3XAttributeMaskNormal | \ kQ3XAttributeMaskAmbientCoefficient | \ kQ3XAttributeMaskDiffuseColor | \ kQ3XAttributeMaskSpecularColor | \ kQ3XAttributeMaskSpecularControl | \ kQ3XAttributeMaskTransparencyColor | \ kQ3XAttributeMaskSurfaceTangent \ ) typedef unsigned long TQ3XAttributeMask; QD3D_EXPORT TQ3XAttributeMask QD3D_CALL Q3XAttributeSet_GetMask( TQ3AttributeSet attributeSet); /****************************************************************************** ** ** ** Renderer Draw Context Tools ** ** ** *****************************************************************************/ typedef struct TQ3XDrawRegionPrivate *TQ3XDrawRegion; QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawContext_GetDrawRegion( TQ3DrawContextObject drawContext, TQ3XDrawRegion *drawRegion); typedef enum TQ3XDrawContextValidationMasks { kQ3XDrawContextValidationClearFlags = 0x00000000L, kQ3XDrawContextValidationDoubleBuffer = 1 << 0, kQ3XDrawContextValidationShader = 1 << 1, kQ3XDrawContextValidationClearFunction = 1 << 2, kQ3XDrawContextValidationActiveBuffer = 1 << 3, kQ3XDrawContextValidationInternalOffScreen = 1 << 4, kQ3XDrawContextValidationPane = 1 << 5, kQ3XDrawContextValidationMask = 1 << 6, kQ3XDrawContextValidationDevice = 1 << 7, kQ3XDrawContextValidationWindow = 1 << 8, kQ3XDrawContextValidationWindowSize = 1 << 9, kQ3XDrawContextValidationWindowClip = 1 << 10, kQ3XDrawContextValidationWindowPosition = 1 << 11, kQ3XDrawContextValidationPlatformAttributes = 1 << 12, kQ3XDrawContextValidationForegroundShader = 1 << 13, kQ3XDrawContextValidationBackgroundShader = 1 << 14, kQ3XDrawContextValidationColorPalette = 1 << 15, kQ3XDrawContextValidationAll = ~0 } TQ3XDrawContextValidationMasks; typedef unsigned long TQ3XDrawContextValidation; QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawContext_ClearValidationFlags( TQ3DrawContextObject drawContext); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawContext_GetValidationFlags( TQ3DrawContextObject drawContext, TQ3XDrawContextValidation *validationFlags); /****************************************************************************** ** ** ** Renderer Draw Region Tools ** ** ** *****************************************************************************/ typedef enum TQ3XDevicePixelType { /* These do not indicate byte ordering */ kQ3XDevicePixelTypeInvalid = 0, /* Unknown, un-initialized type */ kQ3XDevicePixelTypeRGB32 = 1, /* Alpha:8 (ignored), R:8, G:8, B:8 */ kQ3XDevicePixelTypeARGB32 = 2, /* Alpha:8, R:8, G:8, B:8 */ kQ3XDevicePixelTypeRGB24 = 3, /* 24 bits/pixel, R:8, G:8, B:8 */ kQ3XDevicePixelTypeRGB16 = 4, /* Alpha:1 (ignored), R:5, G:5, B:5 */ kQ3XDevicePixelTypeARGB16 = 5, /* Alpha:1, R:5, G:5, B:5 */ kQ3XDevicePixelTypeRGB16_565 = 6, /* 16 bits/pixel, R:5, G:6, B:5 */ kQ3XDevicePixelTypeIndexed8 = 7, /* 8-bit color table index */ kQ3XDevicePixelTypeIndexed4 = 8, /* 4-bit color table index */ kQ3XDevicePixelTypeIndexed2 = 9, /* 2-bit color table index */ kQ3XDevicePixelTypeIndexed1 = 10 /* 1-bit color table index */ } TQ3XDevicePixelType; typedef enum TQ3XClipMaskState { kQ3XClipMaskFullyExposed, kQ3XClipMaskPartiallyExposed, kQ3XClipMaskNotExposed } TQ3XClipMaskState; typedef struct TQ3XColorDescriptor { unsigned long redShift; unsigned long redMask; unsigned long greenShift; unsigned long greenMask; unsigned long blueShift; unsigned long blueMask; unsigned long alphaShift; unsigned long alphaMask; } TQ3XColorDescriptor; typedef struct TQ3XDrawRegionDescriptor { unsigned long width; unsigned long height; unsigned long rowBytes; unsigned long pixelSize; TQ3XDevicePixelType pixelType; TQ3XColorDescriptor colorDescriptor; TQ3Endian bitOrder; TQ3Endian byteOrder; TQ3Bitmap *clipMask; } TQ3XDrawRegionDescriptor; typedef enum TQ3XDrawRegionServicesMasks { kQ3XDrawRegionServicesNoneFlag = 0L, kQ3XDrawRegionServicesClearFlag = 1 << 0, kQ3XDrawRegionServicesDontLockDDSurfaceFlag = 1 << 1 } TQ3XDrawRegionServicesMasks; typedef unsigned long TQ3XDrawRegionServices; typedef void (QD3D_CALLBACK *TQ3XDrawRegionRendererPrivateDeleteMethod)( void *rendererPrivate); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetDeviceScaleX( TQ3XDrawRegion drawRegion, float *deviceScaleX); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetDeviceScaleY( TQ3XDrawRegion drawRegion, float *deviceScaleY); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetDeviceOffsetX( TQ3XDrawRegion drawRegion, float *deviceOffsetX); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetDeviceOffsetY( TQ3XDrawRegion drawRegion, float *deviceOffsetX); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetWindowScaleX( TQ3XDrawRegion drawRegion, float *windowScaleX); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetWindowScaleY( TQ3XDrawRegion drawRegion, float *windowScaleY); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetWindowOffsetX( TQ3XDrawRegion drawRegion, float *windowOffsetX); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetWindowOffsetY( TQ3XDrawRegion drawRegion, float *windowOffsetY); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_IsActive( TQ3XDrawRegion drawRegion, TQ3Boolean *isActive); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetNextRegion( TQ3XDrawRegion drawRegion, TQ3XDrawRegion *nextDrawRegion); /* * One of the next two functions must be called before using a draw region */ /* * Use this Start function if double buffering/image access services from the * Draw Context are not needed, you may still request clear for example */ QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_Start( TQ3XDrawRegion drawRegion, TQ3XDrawRegionServices services, TQ3XDrawRegionDescriptor **descriptor); /* * Use this Start function if double buffering or image access services from * the Draw Context are needed. */ QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_StartAccessToImageBuffer( TQ3XDrawRegion drawRegion, TQ3XDrawRegionServices services, TQ3XDrawRegionDescriptor **descriptor, void **image); /* * This function is used to indicate that access to a DrawRegion is ended. */ QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_End( TQ3XDrawRegion drawRegion); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetDeviceTransform( TQ3XDrawRegion drawRegion, TQ3Matrix4x4 **deviceTransform); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetClipFlags( TQ3XDrawRegion drawRegion, TQ3XClipMaskState *clipMaskState); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetClipMask( TQ3XDrawRegion drawRegion, TQ3Bitmap **clipMask); #if defined(WINDOW_SYSTEM_MACINTOSH) && WINDOW_SYSTEM_MACINTOSH QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetClipRegion( TQ3XDrawRegion drawRegion, RgnHandle *rgnHandle); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetGDHandle( TQ3XDrawRegion drawRegion, GDHandle *gdHandle); #endif /* WINDOW_SYSTEM_MACINTOSH */ QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetRendererPrivate( TQ3XDrawRegion drawRegion, void **rendererPrivate); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_SetRendererPrivate( TQ3XDrawRegion drawRegion, const void *rendererPrivate, TQ3XDrawRegionRendererPrivateDeleteMethod deleteMethod); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_SetUseDefaultRendererFlag( TQ3XDrawRegion drawRegion, TQ3Boolean flag); QD3D_EXPORT TQ3Status QD3D_CALL Q3XDrawRegion_GetUseDefaultRendererFlag( TQ3XDrawRegion drawRegion, TQ3Boolean *useDefaultRenderingFlag); /****************************************************************************** ** ** ** Renderer Class Methods ** ** ** *****************************************************************************/ /* * Methods from Object * kQ3XMethodTypeObjectClassRegister * kQ3XMethodTypeObjectClassUnregister * kQ3XMethodTypeObjectNew * kQ3XMethodTypeObjectDelete * kQ3XMethodTypeObjectRead * kQ3XMethodTypeObjectTraverse * kQ3XMethodTypeObjectWrite * * Methods from Shared * kQ3MethodTypeSharedEdited * * Renderer Methods * * The renderer methods should be implemented according to the type * of renderer being written. * * For the purposes of documentation, there are two basic types of * renderers: * * Interactive * Interactive Renderer * WireFrame Renderer * * Deferred * a ray-tracer * painter's algorithm renderer (cached in a BSP triangle tree) * an artistic renderer (simulates a pencil drawing, etc.) * * The main difference is how each renderer handles incoming state and * geometry. * * An interactive renderer immediately transforms, culls, and shades * incoming geometry and performs rasterization. For example, in a * single-buffered WireFrame renderer, you will see a new triangle * immediately after Q3Triangle_Draw (if it's visible, of course). * * A deferred renderer caches the view state and each geometry, * converting into any internal queue of drawing commands. Rasterization * is not actually performed until all data has been submitted. * * For example, a ray-tracer may not rasterize anything until the * end of the rendering loop, or until an EndFrame call is made. */ /****************************************************************************** ** ** ** Renderer User Interface Methods ** ** ** *****************************************************************************/ /* * kQ3XMethodTypeRendererIsInteractive * * There is no actual method with this - the metahandler simply returns * "(TQ3XFunctionPointer)kQ3True" for this "method" if the renderer is * intended to be used in interactive settings, and * "(TQ3XFunctionPointer)kQ3False" otherwise. * * If neither value is specified in the metahandler, the renderer * is *assumed to be non-interactive*!!! * * OPTIONAL */ #define kQ3XMethodTypeRendererIsInteractive Q3_METHOD_TYPE('i','s','i','n') /* * TQ3XRendererModalConfigureMethod * * This method should pop up a modal dialog to edit the renderer settings * found in the renderer private. * * dialogAnchor - is platform specific data passed by the client to support * movable modal dialogs. * MacOS: this is a callback to the calling application's event handler. * The renderer calls this function with events not handled by the * settings dialog. This is necessary in order to support movable modal * dialogs. An application's event handler must return kQ3True if it * handles the event passed to the callback or kQ3False if not. * An application which doesn't want to support a movable modal configure * dialog should pass NULL for the clientEventHandler of TQ3DialogAnchor. * A renderer should implement a non-movable style dialog in that case. * Win32: this is the HWND of the owning window (typically an application's * main window). (Win32 application modal dialogs are always movable.) * canceled - returns a boolean inditacating that the user canceled the * dialog. * * OPTIONAL */ #define kQ3XMethodTypeRendererModalConfigure \ Q3_METHOD_TYPE('r','d','m','c') typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererModalConfigureMethod)( TQ3RendererObject renderer, TQ3DialogAnchor dialogAnchor, TQ3Boolean *canceled, void *rendererPrivate); /* * kQ3XMethodTypeRendererGetNickNameString * * Allows an application to collect the name of the renderer for * display in a user interface item such as a menu. * * If dataBuffer is NULL actualDataSize returns the required size in * bytes of a data buffer large enough to store the renderer name. * * bufferSize is the actual size of the memory block pointed to by * dataBuffer * * actualDataSize - on return the actual number of bytes written to the * buffer or if dataBuffer is NULL the required size of dataBuffer * * OPTIONAL */ #define kQ3XMethodTypeRendererGetNickNameString \ Q3_METHOD_TYPE('r','d','n','s') typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererGetNickNameStringMethod)( unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize); /* * kQ3XMethodTypeRendererGetConfigurationData * * Allows an application to collect private configuration data from the * renderer which it will then save. For example in a preference file, * a registry key (on Windows) or in a style template. An application * should tag this data with the renderer's object name. * * If dataBuffer is NULL actualDataSize returns the required size in * bytes of a data buffer large enough to store private data. * * bufferSize is the actual size of the memory block pointed to by * dataBuffer * * actualDataSize - on return the actual number of bytes written to the * buffer or if dataBuffer is NULL the required size of dataBuffer * * OPTIONAL */ #define kQ3XMethodTypeRendererGetConfigurationData \ Q3_METHOD_TYPE('r','d','g','p') typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererGetConfigurationDataMethod)( TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, unsigned long *actualDataSize, void *rendererPrivate); /* * TQ3XRendererSetConfigurationDataMethod * * Allows an application to pass private configuration data which has * previously been obtained from a renderer via * Q3Renderer_GetConfigurationData. For example in a preference file or * in a style template. An application should tag this data with the * renderer's object name. * * bufferSize is the actual size of the memory block pointed to by * dataBuffer * * OPTIONAL */ #define kQ3XMethodTypeRendererSetConfigurationData \ Q3_METHOD_TYPE('r','d','s','p') typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererSetConfigurationDataMethod)( TQ3RendererObject renderer, unsigned char *dataBuffer, unsigned long bufferSize, void *rendererPrivate); /****************************************************************************** ** ** ** Renderer Drawing State Methods ** ** ** *****************************************************************************/ /* * TQ3RendererStartFrame * * The StartFrame method is called first at Q3View_StartRendering * and should: * - initialize any renderer state to defaults * - extract any and all useful data from the drawContext * * If your renderer passed in kQ3RendererFlagClearBuffer at * registration, then it should also: * - clear the drawContext * * When clearing, your renderer may opt to: * - NOT clear anything (if you touch every pixel, for example) * - to clear with your own routine, or * - to use the draw context default clear method by calling * Q3DrawContext_Clear. Q3DrawContext_Clear takes advantage of * any available hardware in the system for clearing. * * This call also signals the start of all default submit commands from * the view. The renderer will receive updates for the default view * state via its Update methods before StartPass is called. * * REQUIRED */ #define kQ3XMethodTypeRendererStartFrame \ Q3_METHOD_TYPE('r','d','c','l') typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererStartFrameMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext); /* * kQ3XMethodTypeRendererStartPass * TQ3XRendererStartPassMethod * * The StartPass method is called during Q3View_StartRendering but after * the StartFrame command. It should: * - collect camera and light information * * If your renderer supports deferred camera transformation, camera is the * main camera which will be submitted in the hierarchy somewhere. It * is never NULL. * * If your renderer does not support deferred camera transformation, camera * is the transformed camera. * * If your renderer supports deferred light transformation, lights will be * NULL, and will be submitted to your light draw methods instead. * * This call signals the end of the default update state, and the start of * submit commands from the user to the view. * * REQUIRED */ #define kQ3XMethodTypeRendererStartPass \ Q3_METHOD_TYPE('r','d','s','t') typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererStartPassMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, TQ3GroupObject lightGroup); /* * kQ3XMethodTypeRendererFlushFrame * TQ3XRendererFlushFrameMethod * * This call is only implemented by asynchronous renderers. * * The FlushFrame method is called between the StartPass and EndPass * methods and is called when the user wishes to flush any asynchronous * drawing tasks (which draw to the drawcontext), but does not want * to block. * * The result of this call is that an image should "eventually" appear * asynchronously. * * For asynchronous rendering, this call is non-blocking. * * An interactive renderer should ensure that all received * geometries are drawn in the image. * * An interactive renderer that talks to hardware should force * the hardware to generate an image. * * A deferred renderer should exhibit a similar behaviour, * though it is not required. A deferred renderer should spawn * a process that generates a partial image from the currently * accumulated drawing state. * * However, for renderers such as ray-tracers which generally are * quite compute-intensive, FlushFrame is not required and is a no-op. * * OPTIONAL */ #define kQ3XMethodTypeRendererFlushFrame \ Q3_METHOD_TYPE('r','d','f','l') typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererFlushFrameMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext); /* * kQ3XMethodTypeRendererEndPass * TQ3XRendererEndPassMethod * * The EndPass method is called at Q3View_EndRendering and signals * the end of submit commands to the view. * * If an error occurs, the renderer should call Q3XError_Post and * return kQ3ViewStatusError. * * If a renderer requires another pass on the renderering data, * it should return kQ3ViewStatusRetraverse. * * If rendering was cancelled, this function will not be called * and the view will handle returning kQ3ViewStatusCancelled; * * Otherwise, your renderer should begin completing the process of * generating the image in the drawcontext. If you have buffered * any drawing data, flush it. RendererEnd should have a similar * effect as RendererFlushFrame. * * If the renderer is synchronous: * - complete rendering of the entire frame * if the renderer supports kQ3RendererClassSupportDoubleBuffer * - Update the front buffer * else * - DrawContext will update the front buffer after returning * * If the renderer is asynchronous * - spawn rendering thread for entire frame * if the renderer supports kQ3RendererClassSupportDoubleBuffer, * - you must eventually update the front buffer asynchronously * else * - you must eventually update the back buffer asynchronously * * REQUIRED */ #define kQ3XMethodTypeRendererEndPass \ Q3_METHOD_TYPE('r','d','e','d') typedef TQ3ViewStatus (QD3D_CALLBACK *TQ3XRendererEndPassMethod)( TQ3ViewObject view, void *rendererPrivate); /* * kQ3XMethodTypeRendererEndFrame * TQ3XRendererEndFrame * * This call is only implemented by asynchronous renderers. * * The EndFrame method is called from Q3View_Sync, which is * called after Q3View_EndRendering and signals that the user * wishes to see the completed image and is willing to block. * * If your renderer supports kQ3RendererFlagDoubleBuffer * - update the front buffer completely * else * - update the back buffer completely * * This call is equivalent in functionality to RendererFlushFrame * but blocks until the image is completed. * * If no method is supplied, the default is a no-op. * * NOTE: Registering a method of this type indicates that your renderer will * be rendering after Q3View_EndRendering has been called. * * OPTIONAL */ #define kQ3XMethodTypeRendererEndFrame \ Q3_METHOD_TYPE('r','d','s','y') typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererEndFrameMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3DrawContextObject drawContext); /* * The RendererCancel method is called after Q3View_StartRendering * and signals the termination of all rendering operations. * * A renderer should clean up any cached data, and cancel all * rendering operations. * * If called before Q3View_EndRendering, the RendererEnd method * is NOT called. * * If called after Q3View_EndRendering, the renderer should kill * any threads and terminate any further rendering. * * REQUIRED */ #define kQ3XMethodTypeRendererCancel \ Q3_METHOD_TYPE('r','d','a','b') typedef void (QD3D_CALLBACK *TQ3XRendererCancelMethod)( TQ3ViewObject view, void *rendererPrivate); /****************************************************************************** ** ** ** Renderer DrawContext Methods ** ** ** *****************************************************************************/ /* * kQ3XMethodTypeRendererPush * TQ3XRendererPushMethod * * kQ3XMethodTypeRendererPop * TQ3XRendererPopMethod * * These methods are called whenever the graphics state in the view * is pushed or popped. The user may isolate state by calling: * * Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &red, view); * Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &blue, view); * Q3Attribute_Submit(kQ3AttributeTypeSpecularColor, &white, view); * Q3Box_Submit(&unitBox, view); * Q3TranslateTransform_Submit(&unitVector, view); * Q3Push_Submit(view); * Q3Attribute_Submit(kQ3AttributeTypeDiffuseColor, &blue, view); * Q3Attribute_Submit(kQ3AttributeTypeTransparencyColor, &green, view); * Q3Box_Submit(&unitBox, view); * Q3Pop_Submit(view); * Q3TranslateTransform_Submit(&unitVector, view); * Q3Box_Submit(&unitBox, view); * * or by submitting a display group which pushes and pops. * * If you support RendererPush and RendererPop in your renderer: * - you must maintain your drawing state as a stack, as well. * - you will not be updated with the popped state after * RendererPop is called. * * If you do not support Push and Pop in your renderer: * - you may maintain a single copy of the drawing state. * - you will be updated with changed fields after the view stack is * popped. * * A renderer that supports Push and Pop gets called in the following * sequence (from example above): * * RendererUpdateAttributeDiffuseColor(&red,...) * RendererUpdateAttributeTransparencyColor(&blue,...) * RendererUpdateAttributeSpecularColor(&white,...) * RendererUpdateMatrixLocalToWorld(...) * RendererSubmitGeometryBox(...) * RendererPush(...) * RendererUpdateAttributeDiffuseColor(&blue,...) * RendererUpdateAttributeTransparencyColor(&green,...) * RendererSubmitGeometryBox(...) * RendererPop(...) * RendererUpdateMatrixLocalToWorld(...) * RendererSubmitGeometryBox(...) * * A renderer that does not supports Push and Pop gets called in the * following sequence: * * RendererUpdateAttributeDiffuseColor(&red,...) * RendererUpdateAttributeTransparencyColor(&blue,...) * RendererUpdateAttributeSpecularColor(&white,...) * RendererUpdateMatrixLocalToWorld(...) * RendererSubmitGeometryBox(...) * RendererUpdateAttributeDiffuseColor(&blue,...) * RendererUpdateAttributeTransparencyColor(&green,...) * RendererSubmitGeometryBox(...) * RendererUpdateAttributeDiffuseColor(&red,...) * RendererUpdateAttributeTransparencyColor(&blue,...) * RendererUpdateMatrixLocalToWorld(...) * RendererSubmitGeometryBox(...) * */ #define kQ3XMethodTypeRendererPush \ Q3_METHOD_TYPE('r','d','p','s') typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererPushMethod)( TQ3ViewObject view, void *rendererPrivate); #define kQ3XMethodTypeRendererPop \ Q3_METHOD_TYPE('r','d','p','o') typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererPopMethod)( TQ3ViewObject view, void *rendererPrivate); /****************************************************************************** ** ** ** Renderer Cull Methods ** ** ** *****************************************************************************/ /* * kQ3XMethodTypeRendererIsBoundingBoxVisible * TQ3XRendererIsBoundingBoxVisibleMethod * * This method is called to cull complex groups and geometries * given their bounding box in local space. * * It should transform the local-space bounding box coordinates to * frustum space and return a TQ3Boolean return value indicating * whether the box appears within the viewing frustum. * * If no method is supplied, the default behavior is to return * kQ3True. * */ #define kQ3XMethodTypeRendererIsBoundingBoxVisible \ Q3_METHOD_TYPE('r','d','b','x') typedef TQ3Boolean (QD3D_CALLBACK *TQ3XRendererIsBoundingBoxVisibleMethod)( TQ3ViewObject view, void *rendererPrivate, const TQ3BoundingBox *bBox); /****************************************************************************** ** ** ** Renderer Object Support Methods ** ** ** *****************************************************************************/ /* * Drawing methods (Geometry, Camera, Lights) * */ /* * Geometry MetaHandler * * This metaHandler is required to support * * kQ3GeometryTypeTriangle * kQ3GeometryTypeLine * kQ3GeometryTypePoint * kQ3GeometryTypeMarker * kQ3GeometryTypePixmapMarker * * REQUIRED */ #define kQ3XMethodTypeRendererSubmitGeometryMetaHandler \ Q3_METHOD_TYPE('r','d','g','m') typedef TQ3XFunctionPointer (QD3D_CALLBACK *TQ3XRendererSubmitGeometryMetaHandlerMethod)( TQ3ObjectType geometryType); /* * The TQ3XRendererSubmitGeometryMetaHandlerMethod switches on geometryType * of kQ3GeometryTypeFoo and returns methods of type: */ typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererSubmitGeometryMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3GeometryObject geometry, const void *publicData); /* * Camera MetaHandler * * This metaHandler, if supplied, indicates that your renderer * handles deferred transformation of the main camera within a scene. * * If not supplied, or an unsupported camera is used, the view will do * the transformation for the renderer and pass in a camera in the * StartPass method. * * OPTIONAL */ #define kQ3XMethodTypeRendererSubmitCameraMetaHandler \ Q3_METHOD_TYPE('r','d','c','m') typedef TQ3XFunctionPointer (QD3D_CALLBACK *TQ3XRendererSubmitCameraMetaHandlerMethod)( TQ3ObjectType cameraType); /* * The TQ3XRendererSubmitCameraMetaHandlerMethod switches on cameraType * of kQ3CameraTypeFoo and returns methods of type: */ typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererSubmitCameraMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3CameraObject camera, const void *publicData); /* * Light MetaHandler * * This metaHandler, if supplied, indicates that your renderer * handles deferred transformation of lights within a scene. * * If an unsupported light is encountered, it is ignored. * * OPTIONAL */ #define kQ3XMethodTypeRendererSubmitLightMetaHandler \ Q3_METHOD_TYPE('r','d','l','g') typedef TQ3XFunctionPointer (QD3D_CALLBACK *TQ3XRendererSubmitLightMetaHandlerMethod)( TQ3ObjectType lightType); /* * The TQ3XRendererSubmitLightMetaHandlerMethod switches on lightType * of kQ3LightTypeFoo and returns methods of type: */ typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererSubmitLightMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3LightObject light, const void *publicData); /* * * Update methods * * They are called whenever the state has changed. If the renderer supports * the RendererPush and RendererPop methods, it must maintain its own state * stack. Updates are not called for changed data when the view stack is * popped. * * See the comments for the RendererPush and RendererPop methods above * for an example of how data is updated. * */ /* * Style */ #define kQ3XMethodTypeRendererUpdateStyleMetaHandler \ Q3_METHOD_TYPE('r','d','y','u') typedef TQ3XFunctionPointer (QD3D_CALLBACK *TQ3XRendererUpdateStyleMetaHandlerMethod)( TQ3ObjectType styleType); /* * The TQ3XRendererUpdateStyleMetaHandlerMethod switches on styleType * of kQ3StyleTypeFoo and returns methods of type: */ typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererUpdateStyleMethod)( TQ3ViewObject view, void *rendererPrivate, const void *publicData); /* * Attributes */ #define kQ3XMethodTypeRendererUpdateAttributeMetaHandler \ Q3_METHOD_TYPE('r','d','a','u') typedef TQ3XFunctionPointer (QD3D_CALLBACK *TQ3XRendererUpdateAttributeMetaHandlerMethod)( TQ3AttributeType attributeType); /* * The TQ3XRendererUpdateStyleMetaHandlerMethod switches on attributeType * of kQ3AttributeTypeFoo and returns methods of type: */ typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererUpdateAttributeMethod)( TQ3ViewObject view, void *rendererPrivate, const void *publicData); /* * Shaders */ #define kQ3XMethodTypeRendererUpdateShaderMetaHandler \ Q3_METHOD_TYPE('r','d','s','u') typedef TQ3XFunctionPointer (QD3D_CALLBACK *TQ3XRendererUpdateShaderMetaHandlerMethod)( TQ3ObjectType shaderType); /* * The TQ3XRendererUpdateShaderMetaHandlerMethod switches on shaderType * of kQ3ShaderTypeFoo and returns methods of type: */ typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererUpdateShaderMethod)( TQ3ViewObject view, void *rendererPrivate, TQ3Object *shaderObject); /* * Matrices */ #define kQ3XMethodTypeRendererUpdateMatrixMetaHandler \ Q3_METHOD_TYPE('r','d','x','u') typedef TQ3XMetaHandler TQ3XRendererUpdateMatrixMetaHandlerMethod; /* * The TQ3XRendererUpdateShaderMetaHandlerMethod switches on methods * of the form kQ3MethodTypeRendererUpdateMatrixFoo: */ #define kQ3XMethodTypeRendererUpdateMatrixLocalToWorld \ Q3_METHOD_TYPE('u','l','w','x') #define kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverse \ Q3_METHOD_TYPE('u','l','w','i') #define kQ3XMethodTypeRendererUpdateMatrixLocalToWorldInverseTranspose \ Q3_METHOD_TYPE('u','l','w','t') #define kQ3XMethodTypeRendererUpdateMatrixLocalToCamera \ Q3_METHOD_TYPE('u','l','c','x') #define kQ3XMethodTypeRendererUpdateMatrixLocalToFrustum \ Q3_METHOD_TYPE('u','l','f','x') #define kQ3XMethodTypeRendererUpdateMatrixWorldToFrustum \ Q3_METHOD_TYPE('u','w','f','x') /* * and returns methods of type: */ typedef TQ3Status (QD3D_CALLBACK *TQ3XRendererUpdateMatrixMethod)( TQ3ViewObject view, void *rendererPrivate, const TQ3Matrix4x4 *matrix); #ifdef __cplusplus } #endif /* __cplusplus */ #if defined(OS_MACINTOSH) && OS_MACINTOSH #if defined(__xlc__) || defined(__XLC121__) #pragma options enum=reset #pragma options align=reset #elif defined(__MWERKS__) #pragma enumsalwaysint reset #pragma options align=reset #elif defined(__MRC__) || defined(__SC__) #if PRAGMA_ENUM_RESET_QD3DRENDER #pragma options(pack_enums) #undef PRAGMA_ENUM_RESET_QD3DRENDER #endif #pragma options align=reset #endif #endif /* OS_MACINTOSH */ #endif /* QD3DRenderer_h */